1,000+ Great Games

home *** CD-ROM | disk | FTP | other *** search

/ 1,000+ Great Games / 1_1000 Games.iso / DOSGAMES / DCGAMES4.ZIP / DCSCRIPT.DOC < prev next >

Wrap

Text File | 1995-10-02 | 73.8 KB | 2,696 lines

Introduction 1 Preface 1 Document Organization 1 Conventions 2 Getting Help 2 Basic Information 3 What is a script? 3 What is a script used for? 3 Character scripts 3 Object scripts 4 World script. 5 Control script 5 Magic Spells 5 Game Initialization Script 6 Dead and Resurrection 6 Basic Script Elements 7 Keywords 7 Keywords Table 8 Comments 8 Numbers 9 Tokens 9 Variables 10 Generic Variables (Local and Global) 10 String Variables 10 World Variables and Attributes 11 Object Variables and Attributes 11 Character Variables and Attributes 13 Group Variables and Attributes 14 Types of Scripts 15 Introduction Script 15 Character Script 16 Object Script 17 World Script 18 Control Script 18 Resurrection Script 18 Writing Scripts 19 Script Files 19 Expressions and Assignments 20 Function Table 21 Statements 22 Conditional Statements 22 Flow Control Statements 23 Flow control using if 23 Flow control using on-goto 23 Loop Control Statements 24 The while statement 24 The for statement 24 The foreach statement 24 Object Manipulation Statements 25 Move and Copy 25 Drop 25 Output Statements 25 Write and Writeln 25 Display 26 Input Statements 26 Getstr and Getnum 26 Select 26 Going Places 26 Animation 27 Entering Doors 27 Teleportation 27 Advanced Topics 27 Entry Points 27 Calling A DOS program 28 Creating New Types and Classes 29 New Character Types 29 New Character Classes 29 New Object Types 30 New Object Classes 30 New Object Modifiers 31 New World Types 32 Shareware Opportunities 33 Extending the magic system 33 MS-DOS based extensions 33 Writing a whole new system 34 D C - G A M E S Version 4.0 SCRIPT LANGUAGE USER'S GUIDE August 1995 (c) DC Software, 1989-1995 7908 Kettlewood Court Plano TX 75025 (214) 491-1579Introduction Preface One of the goals of the DCGAMES adventure and role-playing game building system is to provide an environment in which you can create adventure games without having to know anything about computer programming, and without having to maintain a zillion lists of cryptic numbers. If you want to draw a river, you just do it. If you want to create a dragon, just grab the right picture and do it. The idea is to have a large enough set of objects, characters, monsters and landscaping to allow you to concentrate on the story. While this works fine most of the time, it is almost inevitable that there will be a few things you need to do that I didn't think of, or which need to work slightly different. You may need a new type of character or object, or some new magic spells. Maybe the wizards are too wimpy or elves and dwarfs should not exist in your adventure. Most of the features in the DCGAMES system are handled by scripts. The script language is a simple yet powerful language that the game driver understands, and which control the behavior of most parts of the game system. The scripts are created using a standard text editor, and can be as simple or complex as you need them to be. While you can write a complete game without writing a single line of script, a small effort on your part to learn how to write script will result in significantly better games, since you can fine-tune your creation to work exactly the way you want it to work. Document Organization This manual is organized in several sections. The first one is an introduction to the elements of the DCGAMES system. It explains each of the building blocks used to create an adventure, and how (and why) you would want to customize them. Everyone should read this section! The second section is a Reference Manual, which is a list of the features of the script language in a logical order. You will need a printed copy of that section of the manual when you are actually writing a script. Conventions In this document, the following conventions are used: UPPER-CASE-WORDS represent tokens that have a specific value and are typed exactly as shown. italic-words are used when a new concept is being introduced, and the world in italics is the name of that concept. They are also used to indicate that you should be replace the word with an appropriate name or value. bold-words represent names or values that should be typed exactly as shown. text1 | text2 items separated by a vertical bar (|) mean you get to choose one of them. [text1 ] items enclosed in square brackets are optional. If multiple items are listed, separated by a vertical bar, then you may choose one of them or none. { text1 | text2 } items enclosed in curly braces are NOT optional. You must select one of the items listed. ... three dots (ellipsis) indicate that the previous item can be repeated multiple times. If there is a limit to the number of times an item can be repeated, it will be indicated in a note near the area where the ellipsis were used. Getting Help Registered users of DCGAMES get free telephone assistance evenings and weekends. This assistance may range from explaining how a certain feature works to guidance in how to add a new feature. I might even write some specialized scripts for you (within reason). Non-registered users are welcome to call also. I will try to answer questions over the phone, but please keep your questions simple and organized. If you feel you can't afford to pay for the game, I've been known to accept a smaller amount or even waive the fee in exchange for some serious feed back or some outstanding artwork or sound recordings that I may incorporate into the shareware product.Basic Information Who should read this guide? You need to read this guide if you are already familiar with the DCGAMES system and are ready to extend or modify the system to suit a particular game's requierments. It is very important that you be familiar with the world builder program (DCWORLD) before you try to modify the scripts. What is a script? A script is a text file, created using a simple text editor (If you use a word processor, be sure to store the file in 'ASCII' or 'PLAIN TEXT' format). The script file contains the instructions that tell the game driver (DCPLAY program) how to handle most aspects of the game. The system includes a large number of predefined scripts to handle objects, characters, worlds, etc. You can modify these scripts to meet your game's individual requirements, and you can write whole new scripts to extend the number of options you have. The DCGAMES system includes a large set of predefined scripts which are used to handle your game. While these scripts are complete, you may want to modify them or write new scripts to handle your specific needs. The type of script you write depends on the aspect of the game that you want to control. The script language was designed to be easy to learn and use. The documentation was written specifically for people that have no prior exposure to programming, and the predefined scripts have extensive annotations to help you understand them and learn from them. A good thing to remember is that you cannot cause any damage through experimentation. The worst you can do is to make some changes to a script that prevent it from operating properly. All you have to do is retrieve a copy of the original script (which you saved before you modified the script, right? right!) or at worst, you can give me a call and I will help you fix it. Don't be afraid to try! What types of scripts are there? Every aspect of the game is controled by scripts to a large extent. These scripts call other scripts which in turn may call other scripts themselves. Control scripts The CONTROL script is called every time you click with the mouse or press a key on the keyboard. This script decides what action to take based on your input. Thus, while the default control script interprets the letter A to mean 'attack' and a click in the view area with the left mouse button to mean 'look-at', you can modify the complete interface to do whatever you want. The control script is also called every 'minute' of game play. Using the world builder you can specify how time flows in your game (# of moves per minute, # of minutes per hours, # of hours per day, # of days per month, # of months per year, current date, etc.). The game driver then invokes the control script to keep track of time and allow it to take time dependent actions. Game Initialization Script When the game first starts, the INITGAME script will be invoked. This script is used to present the game's story. You can use voice, music, graphics, text, animation, etc. Within this script you also have the chance to create and customize the player's character or even the whole party. The default character stored in record 0 of the statistics file (PLAYERS.DTA) will be used if you don't create one. Dead and Resurrection The RESURECT script is invoked whenever all members of the party die. In this script you have the chance to load a saved game, restart the game from the begining or even resurect the party members. The default resurection script will restore the party members a limited number of times by comparing the number of times they have been resurected with the current experience level. It then transports the party to the place where the game started. Remember that you can set the rules and do whatever you want. Some games I've seen will reduce an individual's experience as a penalty for resurection but leave them where they were. Others will teleport the party to a different location for resurection. Character scripts. When the control script determines that you want to interact with another character, it invokes the character's script to handle the interaction. Every character in your game has a character type that determines it's behaviour. The list of character types is defined in the DCCTOKEN.DAT file and the behaviour is handled by a script with the same name as the character type. DCGAMES includes a full set of character types with their respective scripts: Regular, Bartender, Beggar, Civilian, Guard, Healer, Merchant, Prisoner, Teller and Trainer. The behavior of these character types is described in detail in the DCGAMES Player's Guide. One of the best ways to become quickly familiar with the script language is to compare the description of the character type as documented in the Player's Guide with the actual script that makes the character behave that way. To create your own character types, you add the name of the character type to the list in DCCTOKEN.DAT and then create a script with that name to handle it's behaviour. If a name is longer than 8 characters, you use the first 8 characters for the script name. Note: individual characters can have their own individual script to override some or all of the character's standard behaviour. When a character has it's own script, the driver allows the character's script to handle the behaviour and invokes the default script for the character's type only if the individual script does not handle a particular action. Object scripts. When the control script determines that you want to use an object in some way, it invokes the object's script to handle the action. If the action is on an object you are carrying, the CURRITEM script is invoked. If the action is on an object you are not carrying, the OBJECT script is invoked. These two scripts handle the standard behaviour for all of the object types defined in DCCTOKEN.DAT. You can add new types to the list and modify these scripts to handle actions on the new object types. The default scritps handle Food, Weapon, Ammunition, Armor, Shield, Amulet, Ring, Potion, Scroll, Staff, Chest, Keys, Gems, Book, Gold Sack, Torch, Lantern, Rope, Hooks, Mirror, Sign, Vehicle, Thing, Door and Fence objects. You can also override an object's default behaviour by providing a tailor-made script for that particular object. Any action that is not handled by your script will be handed over to the default script for handling. You can alter the behavior of an object in several ways. You may modify the OBJECT.SCR to alter the way existing objects types work, or define new object types; You can also create a brand new script file to control the behavior of a specific object. World scripts. When the player enters or exists a world, the world's script is executed. The predefined script WORLDDEF.SCR is executed if you don't provide one of your own. The world's script can deny access to the world, or send the character to a different destination within the same world or in any other world. The file DCCTOKEN.DAT contains a list of world types (Outdoors, City, Town, Dungeon, Hideout, House, Castle, Arena, Haunted and End-Game) which you can modify at will. The world script handles entry and exit from each world, but other scripts are also involved. For example, the CONTROL script will generate random monsters only in OUTDOORS, DUNGEON and HAUNTED worlds. It also handles walking of the 'edge' of the world (if outdoors you wrap around to the other edge of the world, but in cities and towns you 'leave' the world). Magic Spells When you invoke magic by using an object, the OBJECT and CURRITEM scripts handle the action, but when a magic users 'casts' a spell, no object is involved, so a separate script is used. The CASTING script handles the casting of magic spells. For more information on magic, see the Player's Guide and the World Builder User's Guide. Basic Script Elements This section introduces the basic elements that form the script language. Just like in English you use words to build sentences, and those words are classified into verbs, adjectives, etc, so does the script language use a basic set of elements to build it's sentences. The script language contains the following basic elements: Keywords, Tokens, Constants, Variables, Structures, Statements, Functions, Procedures, Comments. Let's look at each one in turn. Keywords A keyword is a word that has a special meaning in the script language. You cannot change the spelling or meaning of the keyword, because the game system has a specific meaning for it and depends on that meaning. A primary keyword is equivalent to a verb in the English language. It indicates the action taking place. These keywords form the basis of the script language. For example, if, goto, write, etc. A secondary keyword exists only to complement a primary keyword, and has no meaning by itself. For example, the if primary keyword has four secondary keywords associated with itself, namely: then, elsif, else and endif. For example: if player.name = "Henry" and fighting then write("Go Away"); endif; In the above line, the if and write keywords are primary,while then, and endif are secondary because they have a meaning only in relation to the if keyword. (Note that and is also a secondary keyword, but has nothing to do with if I didn't highlight it). A function keyword is used to examine or modify a system value. This is a value that has a meaning to the game system, but you can examine and sometimes modify it to change the way the system behaves. For example, if the keyword fighting in the previous example has a TRUE value if the game system is currently in combat mode (a fight is taking place), so the script displays the words 'Go Away' if the current player's name is Henry and you are fighting. Note that words such as player, npc, object, world,group, etc., are called variables and their qualifiers (like player.name or world.landscape) are called attributes. These are covered elsewhere in this manual. The section Writing Scripts in this manual introduces most of the keywords using simple examples. A detailed description of each keyword can be found in the Script Language Reference Guide. List of Primary, Secondary and Function Keywords1 Comments A comment is a sequence of characters beginning with the character '!'. The exclamation point tells the script language compiler that the text that follows is a comment and should be ignored. Comments are used to document your scripts so they are easier to understand. For example: ! This is a comment ! This is also a comment! All of it.. !!! This is another comment. Note that all text following first ! is part of the comment, including any other ! character. Numbers Numbers are very important in DCGAMES. They are used extensively to identify the attributes of objects and characters. As a rule, numbers can be values between -2147483647 and 2147483647. While this is true for constants, when using numbers, you will usually have to restrict them to be within the range of values allowed for the purpose you are using the number for. For example, a ring object has an attribute called charges which holds the number of times the ring can be used. This attribute can have a value between 0 (no charges left) and 255. Trying to set the charges attribute to 500 will result in a warning message, and assign the maximum allowed value of 255. The range of values that an attribute can take are documented along with each attribute in the section entitled STRUCTURES further on in this chapter. Tokens When you write a script, you frequently need to examine and modify the attributes of objects and characters, or to perform different actions depending on the values of the same. While most of these attributes are numeric, you don't need to remember what each number means. Instead, tokens have been defined that represent the numeric values. In this document, tokens are shown in UPPER CASE. Any name shown in upper case letters can be considered to be a token. For example. The standard product includes a set of pre-defined object types such as FOOD, WEAPON, ARMOR, etc. The game uses a number to represent the object's type (0, 1, 2, 3, etc), but it would be difficult to remember that if you want to create a WEAPON, you need to set the object's type to 1. Thus, a token (namely WEAPON) can be used. A complete list of predefined tokens, their values and their usage can be found in the appendix. If you modify or extend the set of pre-defined element types, you will also add new tokens to the file DCCTOKEN.DAT, which associates the token name with the actual value it is going to represent. Once the name has been added to the file, you no longer have to remember what value you were using for your new 'type' or 'class' or whatever. Variables A variable is a name used to represent a value, just like a token, but the difference is that the variable holds a value, and the value can be modified. For example, an object could have a weight of 100, but you can change that value any time. Variables are shown in bold letters in this document. A variable may have more than one value associated with it (for example, an object has a name, a value, a weight, etc.). The values associated with the variable are called the attributes of the variable. The following paragraphs hold a complete list of all variables, their names, attributes, values and a brief description of the meaning of the associated value. Generic Variables (Local and Global) There are 2048 local variables, named L0 through L2047. They can hold values between -32768 and +32767. They are called local because they exist only during execution of the script. Once the script has been executed, any value you placed in them is lost. Every time a script starts execution, it's local variables are initialized to zero. These variables are used mostly for control purposes and to hold intermediate values. There are 2048 global variables, named G0 through G2047. These variables can hold values between -32768 and +32767. They are called global because they exist for the entire duration of the game. If you set one of these variables to a certain value, it will retain that value until you change it again. These variables are used to hold values that are important throughout the life of the game. For example, you might use one of these variables to indicate that a certain action has taken place. Other scripts could then check the value of the variable and take different actions depending on whether the action has taken place or not. String Variables There are 17 string variables, named S0 through S16. They are different from other variables in that they hold TEXT instead of numbers. They are also different in that they are used for some specific purposes, and so, are not "generic". Variable S0 can contain up to 255 characters. While you can use it for any purpose, it is also used to store any text that the player types during conversations, as well as other values. The getstr() script function asks the user to type something, and stores that value in this variable (among other things). Variables S1 through S16 can contain up to 64 characters. These variables hold the 16 lines of text associated with the current object or character. The loadtext() script function will load a given text record and place each of the lines in the corresponding variable. Character Variables and Attributes A character in the adventure can be a simple 'extra', with no other function than to flesh out a story, or it can be an integral part of it. Every character is controlled by a script, and the system includes a large number of predefined scripts to handle different types of characters. Amongst the different types of characters are: Regular, Bartender, Merchant, Civilian, Quester, Beggar, etc. Each of these character types has it's own script, and when you create a character, you will usually select one of these scripts to handle it's behavior. You may extend the functionality of each character type by modifying the scripts, or you can create brand new scripts to handle a brand new type of character. For those characters that are central to the story, you may even want to create a special script that handles their unique behavior. When referring to characters, you may talk about the player or the npc. In any interaction, the player is a member of the game player's party. The npc is the member with which the player is interacting. Character Attributes Description name Name of the character (15 characters max). index* For players, the order in the party. For npcs their location in the list of npcs. type Character Type: (0-255). See tokens in DCCTOKEN.DAT [Character Types] class Character Class (0-255). See tokens in DCCTOKEN.DAT [Character Class] block Tile # from the DCPEOPLE.nnn graphics blocks file used for this character block2 Alternate Tile # used in some instances (under script control only) picture Image file (0-999). If given, the file CPICTnnn.PCX contains the picture. voice Voice file (0-999). If given, the file VOICEnnn.RSP contains the voices. x Character's current horizontal location in the current world. y Character's current vertical locatioin in the current world. count For NPCs only, it's the # of npcs represented by the individual NPC. script Optional SCRIPT for this character. Uses the character type as default. text Optioinal text record (0-n). load/mload Current/Maximum load (how much weight can be carried) str/mstr Current/Normal strength aim/maim Current/Normal aim dex/mdex Current/Normal dexterity spd/mspd Current/Normal speed pwr/mpwr Current/Normal magical power points hp/mhp Current/Normal Hit Points iq/miq Current/Normal intelligence ac/mac Current/Normal Armor Class luk/mluk Current/Normal Luck chr/mchr Current/Normal Charisma exp Current experience points level Current character level poisoned Character is poisoned scared Character is scared paralyzed Character is paralyzed confused Character is confused invisible Character is invisible energy Current energy level (From food. See group.energy for energy from sleep). stats Character statistics record. v0 - v7 Extra variables to be used for any purpose you need. weapon Currently wielded weapon (if any) armor Currently worn armor (if any) shield Currently worn shield (if any) ring Currently worn ring (if any) amulet Currently worn amulet (if any) staff Currently wielded staff (if any) bp Currently selected backpack object (The backpack can hold 16) body Currently selected body object (if any, one of the following 6 objects). Object Variables and Attributes An object is an item that can be manipulated in many different ways during game play. The object's TYPE and CLASS determine what can be done with the object. Most of the behavior of objects is controlled from the predefined script OBJECT. This script can handle objects of type food, weapon, ammunition, shield, armor, ring, amulet, scroll, staff, chest, vehicles, etc. Object Variables Description player.weapon The weapon wielded by the current player (if any). player.armor The armor worn by the current player (if any). player.shield The shield being used by the current player (if any). player.ring The ring being worn by the current player (if any). player.amulet The amulet being worn by the current player (if any). player.staff The staff being used by the current player (if any). player.body The last selected body item (represents one of player.weapon, player.armor, player.shield, player.ring, player.amulet or player.staff. player.bp The last selected backpack item for the current player. The backpack can hold up to 16 items, but only one of them is selected at a time. npc.weapon The weapon wielded by the current npc (if any). npc.armor The armor worn by the current npc (if any). npc.shield The shield being used by the current npc (if any). npc.ring The ring being worn by the current npc (if any). npc.amulet The amulet being worn by the current npc (if any). npc.staff The staff being used by the current npc (if any). npc.body The last selected body item (represents one of npc.weapon, npc.armor, npc.shield, npc.ring, npc.amulet or npc.staff. npc.bp The last selected backpack item for the current npc. The backpack can hold up to 16 items, but only one of them is selected at a time. group.vehicle The vehicle the group is currently on (if any). object The object represented by this variable is not being carried by anyone. It exists on it's own in the current world. curritem The object represented by this variable is being carried by either the player or the npc character, either in the backpack or being worn. It is used when the exact location of the object is not important. Each of the objects listed above has the following attributes associated with it. Thus, you can type: npc.weapon.name, player.bp.count, group.vehicle.type, curritem.class, etc. Object Attributes Description name Name of the object (15 characters max). index* Current position of the object in it's place (world, backpack, etc.) type Object Type (0-255). See DCCTOKEN.DAT section [OBJECT TYPES] class Object Class (0-255). See DCCTOKEN.DAT sections [OBJECT CLASS: x, y] block Tile # from file DCOBJECT.mde used to display the object. picture Image file # (000-999). If given, file OPICTnnn.PCX contains the picture. voice Vioce file # (000-999). Objects can have a sound file also VOICEnnn.RSC weight Current weight of the object. value Current value of the object in Silver Pieces (10sp = 1gp). x Object's horizontal location (when not being carried). y Object's vertical location (when not being carried). count Number of objects represented by this single instance. script Optional script file. Uses OBJECT.SCR and CURRITEM.SCR by default. text Object's text record (if any). endgame For compatibility with DCGAMES 1.x/2.x.. 0=No, 1=on GET, 2=Give. endtext Text block # to be displayed when the game ends due to 'endgame'. v0 - v7 Extra attributes, use for anything you want. m0 - m4 Extra attributes, but you can have a token name associated with one of these. See file DCCTOKEN.DAT for more info. World Variables and Attributes Each world has a certain number of attributes which you can examine and in some cases modify. You can only access the attributes for the world you are currently in. Attribute Description name Name of the current world, text, 15 chars. index* Current world number. type World's type, 0 - 255. Tokens: OUTDOORS, CITY, TOWN, DUNGEON, HIDEOUT, HOUSE, CASTLE, ARENA and ENDGAME. x* Horizontal size (width) of the current world y* Vertical size (height) of the current world block(x,y) Landscaping block # displayed at position x,y density(x,y) Density of landscaping block at position x,y level Minimum player level needed to enter this world. landscape Landscaping file being used (0 to 9) door the door through which you entered the current world. doorx(door#) Horizontal location of the door in the current world. doory(door#) Vertical location of the door in the current world. destinationworld(door#) Destination world # . destinationdoor(door#) Destination door in the destination world. (non-trap doors only) destinationx(door#) Horizontal location in the destination world (trap doors only) destinationy(door#) Vertical location in the destination world (trap doors only) trapdoorswitch(door#) Is non-zero if the door is a TRAP (destinationx/y instead of destinationdoor). entrytext(door#) Text block # displayed when the player enters the world through the door. entrytextswitch(door#) If non-zero, the text is displayed only the first time the door is used. exittext(door#) Text block # displayed when the player exits the world through the door exittextswitch(door#) If non-zero, the text is displayed only the first time the door is used. edgedoor The door through which the player exits the current world by walking 'of-the-edge' of the world, or casting the standard 'exit' spell. Group Variables and Attributes Durng game play, your group can contain anywhere from 1 to 6 characters. Group Attributes Description size* Current number of characters in the group. current Currently selected 'spokesbeing' for the group (0-5). gold Amount of gold being carried (given in silver pieces, 10sp = 1gp). food The total amount of normal (non-magical) food being carried by the party. energy The group's energy, which is replenished with sleep. dead_count Number of times that everyone in the group has died (and thus, how many times they have been resurrected). x Current horizontal location in the current world. y Current vertical location in the current world. moves Total number of moves since the game started. block Tile # from DCSYSTEM.mde (type 'SYS_PARTY') to represent the party during normal game play. vehicle Current vehicle (if any). If the group is riding a vehicle, the vehicle's graphics block is displayed instead of the group's regular block. Types of Scripts This section talks about the different TYPES of scripts you may want to write, and tries to point out WHY you would want to write that kind of script, instead of HOW. The actual script language is presented in the section Script Language Programming Guide later in this manual. Introduction Script The introduction script (INITGAME.SCR) is a script that is executed only the first time you start playing. Like most games, you must start of by telling the game player what the story is about, give some background information, set the mood for the game. Before this script is invoked, a group with a single player is created, taking the attributes from record 0 of the statistics file (PLAYERS.DTA) as created using the DCWORLD program. The INITGAME script is free to modify the default character, as well as add other characters to the group at this time. It can also invoke the edit_character function to allow the player to select a name, character type, character block and starting attributes. You can also modify the group's starting position by seting the X and Y attributes of the group variable, or by using the teleport or enter commands. A typical introductory script would look like this: ! ! FILE : initgame.scr ! readtext( "intro.txt" ); ! Read some text viewpcx ( "intro2" ); ! Show a nice picture music ( "intro2" ); ! Play background music wait ( 120 ); ! Wait until music ends or <SPACE> is pressed ! ! Now, create the player's character by using 'edit_player' ! edit_player( 1, 30, ! points to distribute 9, ! Minimum start attribute value is 9 25, ! Maximum start attribute value is 25 1, ! Allow name to be changed 0, ! Don't allow character class to be changed 1 ! Allow character image to be changed ); ! Allow all stats to be changed (strenght, dexterity, etc.) CONTINUE; ! Continue with normal character creation Note that the READTEXT command has some voice, music and graphics capabilities also. The 'intro.txt' file does not necessarily display a single page of text. Character Script Every character in the game has a script to control it's behavior, except for monsters (type HOSTILE), whose behavior consists of chasing the player and fighting. The world builder assumes that the first 8 characters of the character TYPE can be used as the name of the character's script. Thus a BARTENDER's script is BARTENDE.SCR, and a BEGGAR's script is BEGGAR.SCR. The system provides 11 predefined character scripts, each of which has a unique function. A full explanation of each character 'type' as implemented by the scripts can be found in the DCGAMES User's Guide. Usually, a character script handles conversation. When the player 'talks' to a character, the character takes control of the conversation by means of the script. A merchant, for example, asks if you wish to buy or sell something, while a healer asks if you need to be cured, healed, etc. Special characters may have their own unique script, as is the case of JIMMY in the example adventure. That script does a bit of animation when the character is asked to join the adventurer, and handles special needs of that character. You should print out the character scripts and compare each of them with the description of the character type as given in the User's Guide. You will then understand how the given script implements the behavior. There are three ways of working with character scripts. You can modify the default scripts to alter the behavior of existing character types, you can create a brand new character type, with it's own script, or you can create a unique script for a unique character. Object Script Unlike characters, objects are not requried to have a script associated with them. If they do have one associated, it is invoked first to allow it to handle the interaction. If the script does not handle the interaction, or it does handle it but ends with CONTINUE instead of STOP, or there is no script at all, the system invokes one of the default object handling scripts: OBJECT.SCR is invoked for objects laying around while CURRITEM.SCR is invoked for objects being carried by the player or npc. Every time you create a new object type or even a new class within an object type, you will need to modify the OBJECT and CURRITEM scripts to handle the new object. For example, mirrors currently don't do anything. If you wanted to have a mirror that shows you an area around you, you could create mirror classes. Class 0 would be a normal mirror, while class 1 would invoke a 'view' spell. You can then modify the two scripts to check the class attribute for mirrors and behave accordingly. Note: Since version 4.0 allows one script to call another, this description is not entirely correct. The CONTROL script calls the OBJECT or CURRITEM scripts as needed, and these scripts may call others, like the CASTING script or the DESCOBJ script. Now, if you need to have a given object behave differently, you need to write a separate script for it. The script does not need to handle all actions on that object, just the ones that are different. For example: You want to create a magic ring, but this ring can cast more than one spell. You could write a special script that has an entry point for the @WEAR action (see the programming guide section at the end of this document). When the character wears the ring, your script might display the image of a genie, and ask the player what spell is desired. The script would then perform the appropriate spell. Remember that if a script does not have an entry point for a given action, then a default action is taken. In this case, the default action is to call the CURRITEM script. Thus, all actions would be handled by the CURRITEM script except for WEAR. Remember also that if your script ends with CONTINUE instead of STOP, the default action is taken anyway, so your script doesn't really have to handle the situation. For example, your 'ring' may have a 'random' effect (i.e. you never know what is going to happen when you wear it). To do this, your script would just set the ring's class (which determines it's magical effect) and terminate with CONTINUE. The default action would be taken, and the CURRITEM script would handle the actual magical effect!World Script World scripts are executed whenever you ENTER or EXIT the world. The default world script, WORLDDEF.SCR, is invoked if your world does not have it's own script. The world type and other attributes configured using DCWORLD allow the WORLDDEF script to handle most normal situations. World scripts can be very powerful tools to introduce some amount of 'sequencing' into the game. From within a script you can change landscaping, doors, etc. You can also examine and change every single object and character in that world. You could have a character that exists only after you have performed a certain action. The world script could check to see if you have performed that action every time you enter the world, and create the character only when you have done so. You can even re-route the player to a different destination within the same world, or in a totally different one. See the comments in the WORLDDEF script for a detailed discussion of entering and exiting worlds. Control Script The control script is the most sensitive script of all. It is called under different circumstances and it invokes most of the other scripts itself as needed. This script is invoked: Every 'minute' of game play (as defined in the MovesPerMinute control variable) to keep track of time and handle healing, getting tired, resting, the appearance of random monsters, etc. Every time you press a key or click with the mouse to handle the interaction between the player and the game system. Once for every player during a fight, to handle a player's TURN. Once for every monster during a fight, to handle the monster's TURN. Note: Version 3.x had entry points in the control script for handling a player leaving the party, winning a fight (for experience and random treasure), etc. These entrypoints are no longer needed because version 4.0 is more fully under script control, so these events happen in their appropriate places without special "hooks". Resurrection Script The resurrection script (RESURECT.SCR) is called whenever all members of the playing party die. From this script you have the option to give the player a second chance. Once again, you have complete control over the situation. You can terminate the game, give the player the option to restart, restore or quit, or just restore the player's hit points and continue the game. You can also transport the party to another location, and perform some cleanup activities. Writing Scripts Script Files A script can be written using any regular text editor or word processor. If you use a word processor, you should save the script in ASCII or TEXT format (with no special controls like fonts or page formatting). The script file name should have an extension of .SCR, to indicate it contains a script. Once the script has been saved, you will use the script compiler to translate the script from human readable form (text) into a compact code that the game driver understands. The translated code is written into a file with the same name as the original file, but with extension of .SCO (for SCript Object). For example: C:\DCGAME> edit myscript.scr ... you create the script using some editor ... C:\DCGAME> dir myscript.* Volume in drive C is MYVOLUME Directory of C:\DCGGAME MYSCRIPT SCR 1208 10-29-92 1:25p 1 file(s) 1208 bytes 6920192 bytes free C:\DCGAME> dcc myscript DCGAMES Script Compiler Version 4.0, August 1995 Copyright (c) 1992 DC Software, 7908 Kettlewood Court, Plano TX 75025 Compiling Script <myscript.SCR> Code Size = 179 Data Size = 367 Labels = 25 Compilation successful C:\DCGAME> dir myscript.* Volume in drive C is MYVOLUME Directory of C:\DCGGAME MYSCRIPT SCO 604 10-29-92 1:28p MYSCRIPT SCR 1208 10-29-92 1:25p 1 file(s) 1208 bytes 6920192 bytes free The script MYSCRIPT is now ready to be used in your adventure. Now, every script must be translated in the above manner whenever you modify it, or the changes will not be seen by the game driver. The game driver uses the .SCO file only. To compile ALL the scripts in your current directory, type: C:\DCGAME> for %i in (*.scr) do dcc %i If you are familiar with any programming language at all, the script language will be quite easy to learn, but even if you have never learned any programming language, you should be able to learn how to write scripts without to much trouble. To assist you, the following section sections try to present the script language in easy incremental steps, so you may learn at your own pace. If you get hopelessly lost, give me a call and I will try to assist over the phone, but please give it your best shot and try to have specific questions written down when you call. It will help keep the phone call as short as possible. I urge you to annotate this document wherever you see think something being presented poorly, in the wrong order, or just plain wrong. This section is the most important one because it is the one that enables YOU to write your games. Send me a copy of the pages on which you have made notes and I will gladly correct the problem and send you back a new copy with corrections as soon as they are made. Expressions and Assignments An expression is a list of one or more symbols that represent a single value. The symbols may be variables, attributes, constants, functions or operands. We already know what variables, attributes and constants are. An operand is a symbol that tells the computer that an operation should take place. For example, in the expression 3 * 5 + 2, the * operand tells the computer to multiply the constants 3 and 5, and the symbol + tells the computer to add two values together.. In DCGAMES there are 3 types of expressions, arithmetic, relational. An arithmetic expression is one which takes numeric values (from variables, attributes, constant or functions) and performs an arithmetic operation on them. The arithmetic operands are: *, /, +, - and % (this last representing a modulo operation, or the 'remainder' portion of an integer division). A relational expression is one which compares two numerical expressions and results in a logical value (to be specific, a relational expression will always result in either a zero or a one). A logical value is either zero (meaning FALSE) or non-zero meaning true. Expressions are used in many places, but the most common use of expressions is on the right side of an assignment statement. The second most common use for expressions is as part of a flow control statement, such as if or on, which are examined a bit later. Note that the function keywords listedat the begining of this document can be used almost anywhere that you can use an expresion. A function has a value which is replaced in the position that you use the function itself. It also may have parameters that change the value of the function itself. For example, the function abs( - 3 ) has a value of 3, while the function max(-5,7,2) has a value of 7. This table presents a more detailed description of the functions, but a detailed explanation of each of them is found in the Script Language Reference Manual. Function Table Function Description General General purpose functions abs(expr) Returns the value of the expression without a sign (removes negative signs) adjustments(expr,...) Returns the sum of the attribute adjustments indicated by the expressions find(where,what,type) Find an object or character getnum(str,low,high) Display a message and get a value between low and high from the player. getstr(str,...) Get a string from the player and return the index of the matching one. locate(what) Locate an object or npc character by allowing the player to point to it. Time Related Used to control time during game play MovesPerMinute Number of moves that can be made in one minute of game play. MinutesInAnHour Number of minutes in one hour of game play. HoursInADay Number of hours in a day of game play. DaysInAMonth Number of days in a month of game play. MonthsInAYear Number of months in a year of game play. Year The current year. Month The current month of the current year. Day The current day of the current month. Hour The current hour of the current day. Minute The current minute of the current hour. SunRise The hour of the day at which the sun rises SunSet The hour of the day at which the sun sets Monster Related Used to create random monsters DefStat(0-2) Backpacks that contain likely treasure (usually Potions, Rings and Staffs). DefPack(0-3) The statistics records for SMALL, MEDIUM, LARGE and PIRATE monsters. DefLandBlk(0-4) Graphics blocks for land based monsters (ordered, 0=Easy,4=Very Hard) DefCaveBlk(0-4) Graphics blocks for cave dwelling monsters (ordered) DefWaterBlk(0-4) Graphics blocks for water dwelling monsters. (ordered, 4=Pirate Ship) DefSpookBlk(0-4) Graphics blocks of skeletons, ghosts, etc. (ordered) expr represents any expression that results in a numeric value ... means that any number of the preceding may be listed, separated by commas (up to 255 maximum) The numeric range (0-N) means that a value in the given range must be provided when referring to this variable Examples: ! Increase a player's current level player.level = player.level + 1; ! same as "inc(player.level);" ! When selling an object, increase the group's gold by half the value of the object. group.gold = group.gold - player.bp.value / 2; ! same as "dec( group.gold,player.bp.value/2);" ! Compute the amount of damage done by a weapon, taking into account the wielder's ! strength (assumes this is not a missile weapon), where strength is not important. L25 = npc.weapon.damage + adjustments(npc.str); ! NOTE: Since relational expressions return 0 if false and 1 if true, the following ! expression returns a value between 0 and 7, which is the number of attributes ! of the current npc that exceed 25 points. L7 = npc.str > 25 + npc.aim > 25 + npc.dex > 25 + npc.spd > 25 + npc.pwr > 25 + npc.iq > 25 + npc.chr > 25 + npc.luk > 25; ! Change the character's name to "Henry" player.name = "Henry"; Please note that the last assignment statement assigns a string value to the name attribute. The name and script attributes may only hold string values. Statements Just like the English language, the script language uses words and symbols to build sentences or statements which tell the game driver what to do. A statement is a complete sequence of words and symbols that tell the game driver how to perform a single given action. A complex statement consists of a one or more statements that are grouped together in some fashion to create a more complex one. You are already acquainted with the assignment statement, now let's look at some other ones, grouped by their nature or intended usage. Conditional Statements In most cases, rather than just assign values to variables, what you want to do is take different action depending on certain conditions: ! Compute the amount of damage done by a weapon, taking into account the wielder's ! strength IF the weapon is a contact weapon (i.e. not a missile weapon). if npc.weapon.class = BLUNT or npc.weapon.class = EDGED then L25 = npc.weapon.damage + adjustments(npc.str); else L25 = npc.weapon.damage; ! No adjustment for strength endif; ! The above might also be accomplished as follows L25 = npc.weapon.damage; if npc.weapon.class = BLUNT or npc.weapon.class = EDGED then L25 = L25 + adjustments(npc.str); endif; ! Now, the following statement displays the current health status of a player if player.hp = 0 then writeln( player.name, " is dead!" ); elsif player.hp = 1 then writeln( player.name, " is unconscious" ); elsif player.hp < player.mhp writeln( player.name, " is hurt, but still able to function" ); else writeln( player.name, " is healthy" ); endif; Flow Control Statements Sometimes, the if statement can result in long and difficult to read statements. In some cases, it is more appropriate to use one of the various forms of the goto or gosub statements to accomplish the same goal. In order to use these statements, you must first declare one or more labels to which the flow of the execution may be transferred. The following examples are equivalent. Flow control using if :AGAIN L3 = getstr( "Sell", "Buy", "Talk" ); if L3 = 0 then ! script for selling goes here elsif L3 = 1 then ! script for buying goes here elsif L3 = 2 then ! script for talking goes here else writeln( "What did you say?" ); endif; goto AGAIN; ! do it again and again, forever. Flow control using on-goto :AGAIN L3 = getstr( "Sell", "Buy", "Talk" ); on L3 goto XSELL, XBUY, XTALK; writeln( "What did you say?" ); goto AGAIN; :XSELL ! script for selling goes here goto AGAIN; :XBUY ! script for buying goes here goto AGAIN; :XTALK ! script for talking goes here goto AGAIN; When a script is large, a single if statement may be several pages long. It is easy to loose track of what you were trying to accomplish. The on-goto statement has the advantage of breaking the logic into separate sections, each self contained and self explanatory. A more complete analysis of the goto, gosub, on-goto and on-gosub statements can be found in the reference guide. Loop Control Statements Whenever you need to perform the same operation multiple times, a loop statement may come in handy. The following code shows a player giving a copy of everything in his/her backpack to the npc character: L6 = 0; ! Start with the first backpack object; :DOIT setbp(player.bp, L6); ! Select the Nth backpack object if player.bp.count then ! If count non-zero, there is an object copy(player.bp,npc); ! Give a copy of the object endif; inc( L6 ); ! Same as L6 = L6 + 1; if L6 < 16 goto DOIT; ! Repeat 16 times The above code uses the goto statement to create a loop that examines the 16 backpack locations for an object and then copies the objects (if they exist) to the npc. The while statement The while statement simplifies loops by providing an easy way of defining a loop without having to declare a label or writing an IF statement. Note that the test for L6 < 16 is made before the statements inside the loop are executed. L6 = 0; while L6 < 16 do setbp( player.bp, L6 ); if player.bp.count then copy( player.bp, npc ); endif; inc( L6 ); endwhile; The for statement The for statement simplifies the loop even more by allowing you to specify both the initial value, the final value and the amount by which the control variable (L6) is to be incremented (or decremented). Thus, the loop becomes: for L6 = 0 to 15 do setbp( player.bp, L6 ); if player.bp.count then copy( player.bp, npc ); endif; endfor; The foreach statement To top it of, the foreach statement allows you to select in sequence every element of a group. In this case, the group is the set of objects in the backpack. The foreach loop is executed once for each element in the player's backpack. Empty slots are not even selected, so no test is needed. Note that if the backpack has NO elements, then the statements inside the loop not executed. This is the best way of examining all the elements of a group. foreach player.bp do copy( player.bp, npc ); endfor; The foreach statement can select: a) All the characters in the player's group, b) All the objects in a character's backpack, c) All the objects a character is wearing, d) All the character's in the current world (but not in the player's group) and e) All the objects in the current world (but not in anyone's backpack). Object Manipulation Statements As you saw in the examples above, sometimes you want to move or copy objects from one place to another. Move and Copy When you move an object, it is removed from it's current place and inserted in the destination, as long as the destination has enough room for it. If there is not enough room or the destination character cannot carry the object, the object is not moved. The copy statement works the same way, but does not delete the object from the source, thus making a copy instead of moving the object. In both cases, you can specify how many objects you want to move. The command will move as many as the destination can possibly hold. If you specify that you want to move or copy more objects than are available in the source, additional objects are created. Drop When you drop an object, it is added to the list of objects in the world that you are in. The object will remain where you put it. There are no temporary objects in DCGAMES. Output Statements Write and Writeln When you want to display a value, you have several ways of doing it. The most simple one is the write or writeln statement. With this statement you can display all attributes and variables as well as text. The following example displays the time of day in the text window (assuming that the day has an even number of hours). if hour < HoursInADay / 2 + 1 then writeln( "The time is ", Hour, ":", Minute, "am" ); else L7 = Hour - HoursInADay / 2; writeln( "The time is ", L7, ":", Minute, "pm" ); endif; Display The display statement will show a list of items in the menu window, with or without numbers or values associated with it. It is useful when you need to show a list of items but are not requesting user input. The many forms of the display statement are documented in the reference guide. Input Statements Frequently, when you display something you are asking the player for directions; During a conversation, you ask the player what they want to talk about; A merchant might display a list of items and ask which you want to buy. Getstr and Getnum The getstr and getnum functions both return a number. The getstr function asks the user to type a string and searches the list of strings you provided. If a match is found, the command returns the index of the matching string (i.e. which one matched). If no match is found, the function returns a -1. In any case, the string is stored in the string variable s0. The getnum function displays a string and asks the user to enter a value in a given range. Only values in the range are allowed. If the user presses Esc instead of typing a number, the function returns -1. Select The select function displays a menu identical to the one displayed by display, but allows the user to select one of the entries by using the arrow keys. This function is used extensively, and you should study it with care in the reference guide. Going Places There are several ways in which characters and objects may move under script control. Animation All characters and any object that is not being carried by a character has a location within the world reflected by the x and y attributes of that character or object. From a script you may modify these attributes and effectively move the characters or objects within the limits of the world they are in. You can also change the block attribute to provide some additional visual feed back (as long as the character is on screen). A small example of animation is presented in the JIMMY.SCR file in the example game. When asked to join the party, Jimmy will walk over to his chest and retrieve his weapons, armor and money. He will then walk back towards the player and join the party. Automatic animation WILL be eventually handled by the system, so don't go writing animation routines for every character in your game. This kind of animation should be used in specific instances where you want things to happen that the user must not be able to prevent or should not have to do him/herself. Entering Doors The player's party may move from one location to another in several ways. The simplest one is to use the Enter command to enter a door. The party will be transferred to the world and destination that the door leads to. NOTE: The party will NOT be transferred to the new location until the script finishes execution. Teleportation If you wish to transfer the player to a specific world, you may use the Teleport command. This command allows you to specify a destination world (by number) as well as either a door in the destination world through which you wish to enter, or the actual x and y location at which the party should appear. Thus, a door need not be present in the destination world. Advanced Topics Entry Points Whenever a script is invoked, execution of the script will begin at a special label which is called an Entry Point. The entry points are labels of the form :@# where # is a number between 0 and 20, but, to make life easier, the labels have specific names associated with them, which make it easier to remember them. The entry points and the names associated with them are different for each type of script, and are shown below: You should use the name form of the entry points unless you have a very good reason for using the numbers. For Character Scripts @TALK (0) - Talk to the character @DROP (2) - Character is being asked to leave the party @CAST (11) - Character will try to cast a given spell. For Object Scripts @TALK (0) - Talk to an object. @GET (1) - Move an object into the player's backpack. @DROP (2) - Drop an object being carried. @WEAR (3) - Wear an object. @REMOVE (4) - Remove an object being worn. @LOOK (5) - Look at an object. @EXAMINE (6) - Examine an object carefully. @INVOKE (7) - Invoke the magic in a magical object (ring, amulet, etc) @USE (9) - Use a generic object for whatever purpose it is intended. @EXIT (10) - The player's party wants to get out of a vehicle. For World Scripts @ENTER (9) - The player's party is entering the current world @EXIT (10) - The player's party is leaving the current world For Control Scripts n/a (0) - Time Control Entry Point. n/a (1) - Party wants to rest for the night. n/a (2) - A member of the party wants to leave the group. For Magic Spells @CAST (11) - A magic user has casts a spell. For Game Initialization n/a (0) - Invoked at game initialization For Dead and Resurrection n/a (0) - Invoked when everyone in the party dies. Calling A DOS program From within a script, you may execute a DOS program by using the system command. This command works exactly like the writeln command, except that instead of sending a line of text to the text window, the text is formed into an MS-DOS command and executed. When the command ends execution, the MS-DOS error level is stored in the failure variable. A value of 0 usually indicates success. See the reference guide entry for additional information. Creating New Types and Classes When the current types and classes of characters, objects or worlds is not enough, you may create your own types and classes as needed. The procedure for doing this is highlighted here, the assumption is made that you have read the manuals and are familiar with the script language before you attempt to add a new type or class. New Character Types To create a new character type, you should edit the file DCCTOKEN.DAT, look for the section [CHARACTER TYPES and add an entry after the last character type in the file: [CHARACTER TYPES] REGULAR 0 ! REGULAR.SCR - Will join the party if asked to.. HOSTILE 1 ! HOSTILE.SCR - Will attack on sight and follow you.. MERCHANT 2 ! MERCHANT.SCR - Buys and Sells stuff.. BARTENDER 3 ! BARTENDE.SCR - Sells beer. Good source of information. HEALER 4 ! HEALER.SCR - Cure, Heal, Resurrect, Remove Curse,.. CIVILIAN 5 ! CIVILIAN.SCR - Will talk, but won't join.. TELLER 6 ! TELLER.SCR - Fortune Teller or Oracle type.. QUESTER 7 ! QUESTER.SCR - Asks you to find an object or person. BEGGAR 8 ! BEGGAR.SCR - Want's money. Might give you a tip. TRAINER 9 ! TRAINER.SCR - Will train someone (STR,DEX,AIM,IQ) GUARD 10 ! GUARD.SCR - Blocks your way unless given the password. PRISONER 11 ! PRISONER.SCR - Will join your party temporarily (to escape). LAWYER 12 In the above segment, the new character type LAWYER has number 12 assigned to it (the next available number). You may now write a script file called LAWYER.SCR to handle the default behaviour of lawyers. New Character Classes Character classes in the current implementation apply only to characters that join the party. The class of the character is used to determine what kind of weapons and armor they can use, what kind of magic they have, how fast they recover, etc. To create a new character class, just edit the DCCTOKEN.DAT file and add the new class to the [CHARACTER CLASSES] section: [CHARACTER CLASSES] HUMAN 0 ! standard stuff, no power ELF 1 ! fast, magical power, not strong DWARF 2 ! slow, STRONG, no magic, no missiles or shields WIZARD 3 ! slow, lot's of magic, not strong ARCHER 4 ! fast, no magic, + on missile weapons FIGHTER 5 ! fast, strong, no magic of any kind THIEF 6 In the above segment, the new character class THIEF has a number 6 (next available one). The DCBLOCK, DCWORLD, DCPLAY and DCREPORT programs will now recognize thieves as a valid character type. You may also want to modify the OBJECT and CASTING scripts to give a thief certain advantages when dealing with traps, and to enable or restrict the kinds of weapons, magic, etc, that the character can handle. New Object Types Creating a new object type is again started by adding the new type to the DCCTOKEN.DAT file. The section [OBJECT TYPES] contains the names and numbers for all object types. Unlike characters, a single script handles all object types and classes. The OBJECT script should be extended to handle the new object type for all it's entry points. The object types Food, Weapon, Armor, Shield, Amulet, Ring and Staff have special treatment because they can be worn by the characters. The Vehicle object type also has special handling because it can be used for transportation. Other than these special handling, you can modify the OBJECT script file as much as you want. New Object Classes An object class is also represented by a section in the DCCTOKEN.DAT file. It is different from other sections in that multiple object types may have the same class (for example: rings, amulets, food, potions and gems all have the same class set). If your new object is going to have the same set of class items that already exists for another type, just add the name to the list, for example: ! ! Magical Effects, Type 1 ! [OBJECT CLASS: FOOD, POTION, RING, AMULET, GEMS, WIDGET] NONE 0 ! No magical effect CURE 1 ! Remove POISON HEAL 2 ! Restore some HP POISON 3 ! (Trap) POISON drinker RESTORE 4 ! Restore ALL HP PLUS_STR 5 ! Increase STRENGTH PLUS_DEX 6 ! Increase DEXTERITY PLUS_SPD 7 ! Increase SPEED PLUS_AIM 8 ! Increase AIM PLUS_AC 9 ! Increase AC PLUS_HP 10 ! Increase HP PLUS_IQ 11 ! Increase IQ PLUS_PWR 12 ! Increase POWER Here, we have added the new object type WIDGET to the set of objects that have personal magic. You still have to modify the OBJECT script to handle the object's class. For example, on object.type goto USE_FOOD, USE_WEAPON, USE_AMMO, USE_ARMOR, USE_SHIELD, USE_AMULET, USE_RING, USE_POTION, USE_SCROLL, USE_STAFF, USE_CHEST, USE_KEYS, USE_GEMS, USE_BOOK, USE_GOLDSACK, USE_TORCH, USE_LANTERN, USE_ROPE, USE_HOOKS, USE_MIRROR, USE_SIGN, USE_VEHICLE, USE_WIDGET; . . . :USE_AMULET :USE_RING :USE_ARMOR :USE_WEAPON :USE_SHIELD :USE_STAFF writeln( "You must first 'get' it, then 'wear' or 'wield' it.." ); STOP; :USE_WIDGET writeln( "If you want to use it, you must first 'get' it.." ); STOP; . . Here, we have decided that a WIDGET must be in the player's backpack before it can be used. If your new object is different from all other objects, you can create a brand new section for it's classes in the DCCTOKEN.DAT file: ! ! My WIDGET object classes ! [OBJECT CLASS: widget] ROUND 0 ! A round widget SQUARE 1 ! A square widget OVAL 2 ! An oval widget At this point, you may create graphics blocks with type widget and class round, square or oval. You may also write script code like this: if object.type = widget then on object.class goto XROUND, XSQUARE, XOVAL; writeln( "Unknown widget class.." ); stop; endif; :XROUND ! Handle a round widget .... STOP; :XSQUARE ! Handle a square widget .... STOP; :XOVAL ! Handle an oval widget .... STOP; New Object Modifiers Each object has 5 attributes that can be used to implement it's differences from other objects. These attributes have names m0 through m4, but the object modifiers section in the DCCTOKEN.DAT file allows you to call them by other names. When you create a new object type and/or class, you may want to create new names for those fields that you might use to differentiate between them For example: [OBJECT MODIFIERS] ! Object Type: FOOD ! 0 Is not used UNITS 1 ! If magical, how many units are affected PERMANENT 2 ! If magical, how long does effect last? (0=one day, 1=permanent) ! 3 Is not used ! 4 Is not used ! Object Type: WEAPON HANDS 0 ! # of hands needed to use the weapon RANGE 1 ! Range of this weapon DAMAGE 2 ! Damage done when using this weapon. AMMONEEDED 3 ! Type of ammunition needed (See AMMOTYPE below..) ! 4 Is not used ! Object Type: WIDGET SIDES 0 ! # of sides that the widget has RANGE 1 ! Range of this widget Note that if you want to use a token that already has a value assigned, like range in the example, which has a value 1 assigned for weapons, you MUST use the same value for the token. Tokens are replaced by their numeric value during compilation, so the following two lines are equivalent: if object.hands = 7 then ... if object.sides = 7 then ... Both lines are comparing the m0 modifier of the object with the value 7. The type of the object is not checked to see that the token you are using belongs to the object's type. New World Types Perhaps the easiest to create would be a new world type. Again, just add the entry to the DCCTOKEN.DAT file, section world types, and then edit the WORLDDEF script file to handle the new world type. Note that many of the currently defined world types have no actual differences between them. For example, Cities, Towns, Hideouts, Houses and Castles are all the same.. You can change that by modifying the appropriate scripts. For example: If you want to make opening a locked chest a crime in Castles and Houses, you can add a check in the OBJECT script to verify the type of world you are in when the character tries to break a lock. Shareware Opportunities While most users will use the script language to make small changes to the game system, with a few customized scripts to handle special characters or objects, the true power of scripts lies in the ability to completely change the way everything works. Here are a few example of some more complex projects that you may want to attempt once you are comfortable writing scripts: Extending the magic system The current magic system allows a character to cast a spell if it has the required number of power points. There is no requirement to learn the spells, or to be at a certain level before you can cast it. You can change the OBJECT and CASTING scripts to handle a magic book, which can be either a class of book (currently, books don't have classes) or a whole new type of object (Magic Book). You can also change the scripts to handle a lot more spells (up to 255 of each type), or add a level requirement for each spell. MS-DOS based extensions The system command allows you to run DOS programs from within a script. The following DOS programs could be called from a script to extend the functionality of the system. Writing these extensions requires knowledge about internal structures of the game files, which I will be glad to provide on a case by case basis. Save/Restore/Restart Replace the prompts that perform this function with a window that shows saved games along with comments and let's you choose which one you want to restore, or lets you specify which slot you want to save in, and what comment you want to associate with the saved game. Character Editor Allows you to examine/modify (i.e. cheat) the PARTY file. Arcade/Casino extensions A completely separate sub-game that is executed when you enter a world. For example, when you enter a casino, you can run a DOS game that allows the user to play poker or some other games in order to make money. The program may read the PARTY file to get the names of the characters and the amount of gold they have. It would update the gold amount when the characters leave the casino. Stand Alone Utilities A nice utility would be one that can take the game and create PCX graphics files for each world, optionally including the objects and characters that appear in it. The PCX file can then be scaled and manipulated by other utilities to print maps or include the graphics in documentation. Writing a whole new system It is perfectly feasible to take the rules, character types, magic system, etc of game systems such as Dungeons and Dragonstm or Man, Myth and Magictm and write them as scripts. You would have to throw away all of the current scripts and write them from scratch, but it's perfectly feasible. Of course, these systems are copyrighted by their respective publishers, so it wouldn't be possible to distribute such a system as shareware (I think, but I'm not a copyright expert). Primary Keywords continue copy dec display drop endgame enter fight find for foreach frame getaction1 getnum getstr goto gosub if inc join leave loadhint loadtext locate move on paint pause readtext restart restore return runscript1 save savepcx1 select setbody setbp stats stop teleport vanish viewfli1 viewpcx voice vplay wait while write writeln Secondary Keywords if - then, elsif, else, endif expression - and, or, xor, not for - to, by, do, endfor foreach - do, endfor while - endwhile select, display - matching paint - screen, window Function Keywords abs action adjustments Day DaysInAMonth DefCaveBlk DefLandBlk DefPack DefSpookBlk DefStat DefWaterBlk fighting failure Hour HoursInADay keypress1 max min Minute MinutesInAnHour Month MonthsInAYear MovesPerMinute pointx1 pointy1 random success SunSet SunRise version Year 1 Keywords marked with a (1) are new in version 4.0 of DCGAMES!